refactor(skill): upgrade open-code-review skill to modular structure with v1.10.1 features by lidaixingchen · Pull Request #850 · alibaba/open-code-review

lidaixingchen · 2026-08-11T17:49:35Z

Summary of Changes

This PR refactors the built-in open-code-review skill into a modular, progressive-disclosure architecture and aligns it with all latest CLI features up to v1.9.1.

Key Enhancements:

Modular Architecture & Token Efficiency:
- Replaces the legacy monolithic SKILL.md with a streamlined main guide using Progressive Reference Navigation.
- Extracted detailed reference documentation into references/:
  - references/flags.md: Comprehensive CLI flags reference for review & scan modes.
  - references/llm-config.md: Installation, LLM configuration, resolution priority, and per-run CLI overrides.
  - references/rules.md: Custom rule definitions, hierarchy, and matching debugging.
  - references/mcp.md: MCP server integration & tool registration specifications.
  - references/troubleshooting.md: Troubleshooting, performance tuning, session management & filtering.
Alignment with v1.9.1 CLI Features:
- Per-Run Overrides: Documented --provider, --model, and --max-tokens CLI flags to override configuration per-run.
- Resumable Scan Mode: Documented ocr scan --resume <session-id> support.
- Comment Filtering & Extraction: Added ocr session comments subcommand options (--severity, --category, --json).
- Advanced Configs: Included llm.retry_codes (custom 4xx retry codes; 408/409/429 and all 5xx are already retried by the SDK) and max_tokens (per-file token cap).
- Preview Support: Updated --preview flag options (supports --format json).
- Protocol Environment Variable Fix: Updated legacy OCR_USE_ANTHROPIC guidance to standard OCR_LLM_PROTOCOL=anthropic.

Follow-up Accuracy Fixes (verified against source):

Fixed retry_codes examples: only 4xx codes are accepted — 429,502,503 would error out; 408/409/429 and all 5xx are retried by the SDK by default.
Fixed ocr session comments flag: it is --json, not --format json.
Fixed JSON status enum: scan mode has no manifest and emits success / completed_with_warnings / completed_with_errors, not the review-mode values.
Fixed exit-code semantics: non-zero only when every selected item failed or on run-level failure; partial failures exit 0.
Clarified that background sanitization (control chars, 2000/8000 char limits) applies to --background-file only; inline --background passes through raw.
Clarified --max-tools min-10 clamp is review-mode only; scan mode takes effect only above the template default.
Enriched JSON output docs: llm, trace_id, tool_calls, project_summary, token breakdown fields, comments.thinking, coverage reused/waived sets, and stderr failure emission.
Added provider-level config (providers.*, custom_providers.*), extended env vars (OCR_LLM_AUTH_HEADER, OCR_LLM_EXTRA_HEADERS, OCR_USE_ANTHROPIC, OCR_LLM_TIMEOUT, OCR_CONFIG_PATH), llm.timeout_sec/auth_header/extra_* keys, and ocr config provider/model/unset commands.
Added session --repo flag, MCP behavioral details, and rules matching details (case-insensitive matching, single-level include/exclude, heuristic file references).
Updated stale model example to claude-opus-5, deferring to ocr llm providers.
Added output truncation handling: redirect-to-file guidance with ocr session comments recovery in Step 2, a Gotchas entry, and a troubleshooting row (covers the topic of docs(skill): avoid output truncation in agent skill instructions #809 with a complete recovery path), plus the official site link.

Reconciliation with main:

Rebased onto the latest main (including feat(llm): add novita api as a default provider #829 novita provider, feat(providers): add siliconflow-cn as a built-in model provider #775 siliconflow-cn provider, and docs(skill): avoid output truncation in agent skill instructions #809 skill doc changes). The two new providers do not change any documented behavior — the docs defer to ocr llm providers.
Resolved the SKILL.md conflict with docs(skill): avoid output truncation in agent skill instructions #809 (both refactored the same file from the same baseline): kept this PR's refactored version and folded the output-truncation topic into it with a more complete handling (redirect to file + ocr session comments recovery). Note docs(skill): avoid output truncation in agent skill instructions #809's "default: Chinese" statement does not match the source — resolveLang("") returns "English" (internal/config/template/template.go).

Authored by 历代星辰

CLAassistant · 2026-08-11T17:49:53Z

All committers have signed the CLA.

github-actions · 2026-08-11T17:49:53Z

✅ OpenCodeReview: Review skipped: no items were selected.

Copilot

Pull request overview

Refactors the skills/open-code-review documentation into a modular “progressive reference navigation” structure and updates the guidance to cover newer CLI capabilities through v1.9.1 (review/scan modes, session resume, per-run overrides, MCP, troubleshooting).

Changes:

Reworked SKILL.md into a slimmer main guide with a navigation table and updated workflows for review vs. scan.
Added dedicated reference docs for flags, LLM configuration, rules, MCP integration, and troubleshooting/session management.
Updated examples to prefer --audience agent and --format json, and documented newer session/comment tooling.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
skills/open-code-review/SKILL.md	Main skill guide refactored to progressive navigation and updated workflows/examples.
skills/open-code-review/references/flags.md	Centralized CLI flags reference and defaults.
skills/open-code-review/references/llm-config.md	Installation + LLM configuration + per-run override documentation.
skills/open-code-review/references/rules.md	Extracted custom rule resolution/format/debugging docs.
skills/open-code-review/references/mcp.md	Documented MCP server configuration and built-in tool registry.
skills/open-code-review/references/troubleshooting.md	Added performance tuning, troubleshooting, and session management guidance.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

+# Resume interrupted review or scan
+ocr review --audience agent --format json --resume <session-id>
+ocr scan --audience agent --format json --resume <session-id>


…for v1.9.1

…TP 5xx notation based on review feedback

- Fix retry_codes examples: accepts 4xx only; 408/409/429 and all 5xx are already retried by the SDK by default - Fix ocr session comments flag: --format json -> --json - Fix JSON status enum: scan mode emits success / completed_with_warnings / completed_with_errors (no manifest) - Fix exit-code semantics: non-zero only on run-level failure or when every selected item failed; partial failures exit 0 - Clarify background sanitization (strip control chars, 2000/8000 char limits) applies to --background-file only; inline -b passes through raw - Clarify --max-tools min-10 clamp applies to review mode only; scan mode only takes effect above the template default - Enrich JSON output structure: llm, trace_id, tool_calls, project_summary, token breakdown fields, comments.thinking, coverage reused/waived sets, and stderr failure emission - Add provider-level config (providers.*, custom_providers.*), extended env vars (OCR_LLM_AUTH_HEADER, OCR_LLM_EXTRA_HEADERS, OCR_USE_ANTHROPIC, OCR_LLM_TIMEOUT, OCR_CONFIG_PATH), llm.timeout_sec / auth_header / extra_* keys, and ocr config provider / model / unset commands - Add session --repo flag, MCP behavioral details, rules matching details - Update stale model example to claude-opus-5; defer to ocr llm providers Signed-off-by: 历代星辰

- Add console truncation prevention guidance in Step 2 (redirect to file, session comments recovery, stderr note) and a Gotchas entry, matching the truncation topic of alibaba#809 with a more complete recovery path - Add Tool Output truncation troubleshooting row - Add official site link to References Signed-off-by: 历代星辰

…ng note - Remove host-specific size estimate (~45KB) from truncation guidance; keep host-agnostic wording since agents vary (Claude Code, Codex, etc.) - Add Windows PowerShell redirect caveat: PowerShell 5 '>' writes UTF-16 and corrupts JSON; use Out-File -Encoding utf8 or bash Signed-off-by: 历代星辰

…language rules

…eshooting

…with v1.10.1 features

…ately

… defaults

lizhengfeng101 · 2026-09-10T09:22:00Z

Thanks a lot for the thorough work here, and apologies for the long delay.

Since this PR was opened, the skill has moved in the opposite direction on main: #1002 deliberately simplified SKILL.md into a single lean file (now ~229 lines) rather than expanding it into a modular references/ structure. The doc topics you covered (e.g. #809's output-truncation guidance) were already folded into main through that path.

Combined with the merge conflicts and the fact that the content targets v1.9.x while the CLI is now at v1.11.7, the modular-refactor direction no longer aligns with where the skill is heading, so I'm going to close this.

That said, the accuracy fixes you found are genuinely valuable (e.g. retry_codes only accepting 4xx, ocr session comments using --json not --format json, the scan-mode status enum, and the exit-code semantics). If you're up for it, a small focused PR with just those corrections against the current main would be very welcome and easy to merge.

Thanks again for the effort and the careful cross-checking against the source.

ydflow · 2026-09-28T01:35:30Z

Thanks for the careful read on the direction, and for calling out the accuracy fixes as worth keeping — that was a fair call.

Opened #1587 as the small focused PR. Only one of the four was still wrong on main:

status enum — the CLI reference listed only success / completed_with_warnings / completed_with_errors / skipped. Those are the pre-manifest path (outputJSON / outputJSONNoFiles); a review run with a manifest reports manifest.TerminalState instead (complete / partial / failed / skipped, internal/session/manifest.go:166 via cmd/opencodereview/output.go:386). So the documented enum was missing the values a real ocr review --format json actually emits. Fixed in all five locales.
retry_codes 4xx-only, session comments --json, and the exit-code semantics are all already correct in pages/ — configuration.md:277, cli-reference.md:442, and the exit-codes table plus faq.md:234 respectively. I verified each against sanitizeRetryCodes (internal/llm/resolver.go:970), the flag registration (cmd/opencodereview/session_cmd.go:207), and reviewResultError (cmd/opencodereview/review_cmd.go:326). Nothing to carry over, so I left them alone rather than re-litigating settled text.

The PR notes that pages/ vitest and typecheck were not run — pages/node_modules is absent in my checkout. The change is Markdown table prose in one row per locale, with make english-check passing (exit 0, 635 files) and LF/UTF-8 confirmed on all five.

Also worth flagging since it came up in the #850 discussion: skills/open-code-review/SKILL.md:246 still suggests ocr config set llm.model claude-opus-4-6, and cli-reference.md uses the same model in its JSON example. I left both as-is — an example model name is a judgment call and not a correctness bug — but mention it in case you'd rather see it track whatever is current.

Copilot AI lite review requested due to automatic review settings August 11, 2026 17:49

Copilot started reviewing on behalf of lidaixingchen August 11, 2026 17:50 View session

Copilot AI reviewed Aug 11, 2026

View reviewed changes

lidaixingchen added 3 commits August 12, 2026 03:17

refactor(skill): upgrade open-code-review skill to modular structure …

a06e9a8

…for v1.9.1

docs(skill): refine review resume example, max-tokens default, and HT…

e61422e

…TP 5xx notation based on review feedback

lidaixingchen force-pushed the refactor/upgrade-skill-to-modular-v1.9 branch from b6d3fd8 to feba657 Compare August 11, 2026 19:18

lidaixingchen added 5 commits August 12, 2026 03:25

docs(skill): sync version to 1.10.0 and add --output flag & extended …

2c3daed

…language rules

docs(skill): polish -o flag documentation, Gotchas, and frontmatter

2b7d291

docs(skill): sync open-code-review skill to v1.10.1

3c866bd

lidaixingchen changed the title ~~refactor(skill): upgrade open-code-review skill to modular structure with v1.9.1 features~~ refactor(skill): upgrade open-code-review skill to modular structure with v1.10.1 features Aug 26, 2026

lidaixingchen added 5 commits August 27, 2026 00:38

docs(skill): fix review resume example to include ref range in troubl…

3c14791

…eshooting

docs(skill): align documentation facts strictly with v1.10.1 source

cb232e6

refactor(skill): upgrade open-code-review skill to modular structure …

f4ed5bb

…with v1.10.1 features

docs(skill): document effort preset, no-filter, and output flag accur…

cfb270b

…ately

docs(skill): update accurate token limits, provider presets, and flag…

2d132ee

… defaults

lizhengfeng101 closed this Sep 10, 2026

ydflow mentioned this pull request Sep 28, 2026

docs(cli-reference): list the manifest status values in the status field #1587

Merged

Navigation Menu

refactor(skill): upgrade open-code-review skill to modular structure with v1.10.1 features - #850

refactor(skill): upgrade open-code-review skill to modular structure with v1.10.1 features#850
lidaixingchen wants to merge 13 commits into
alibaba:mainfrom
lidaixingchen:refactor/upgrade-skill-to-modular-v1.9

lidaixingchen commented Aug 11, 2026 •

edited

Loading

Uh oh!

CLAassistant commented Aug 11, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Aug 11, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

lizhengfeng101 commented Sep 10, 2026

Uh oh!

ydflow commented Sep 28, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Conversation

lidaixingchen commented Aug 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary of Changes

Key Enhancements:

Follow-up Accuracy Fixes (verified against source):

Reconciliation with main:

Uh oh!

CLAassistant commented Aug 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Aug 11, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

lizhengfeng101 commented Sep 10, 2026

Uh oh!

ydflow commented Sep 28, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

lidaixingchen commented Aug 11, 2026 •

edited

Loading

CLAassistant commented Aug 11, 2026 •

edited

Loading